Table of Content

Install & Usage

Develop

F&Q

Embedding "PrintSpirit" Label Editor in Third-Party Websites and Intranet Information Systems

"PrintSpirit" provides a set of APIs that allow the label designer (SpiritDesigner) to be embedded into third-party websites or intranet information systems, offering comprehensive label editing and printing functionalities at a very low cost.

Usage Conditions: Embedding the "PrintSpirit" label editor requires an enterprise account (internet mode) or the installation of SpiritCenter (intranet mode). The development methods for both modes are identical, with the only difference being the server address. The internet mode uses the PrintSpirit official website address: https://www.printspirit.cn, while the intranet mode uses the IP address where SpiritCenter is installed (http://installationIP:9011 or https://installationIP:9443).

Experience

To experience the effect of embedding in a third-party website, please download the Third-Party Website Simulator. This program sets up a simulated website on your local machine, enabling label editing and printing functionalities through PrintSpirit's third-party API. Additionally, the program provides source code, including example programs in GO and PHP, for reference when embedding PrintSpirit. For details, see the usage of the Simulated Third-Party Website Program.

Download the Simulator, which is a green software and can be executed directly.

Open the Windows command line (CMD, PowerShell, etc.).

cd  PATH/to/downloaded_file_directory
.\third_site.exe -p 8000 -ip SpiritCenter_installation_IP_address,
  • -p parameter specifies the web port, default is 8000
  • -ip specifies the SpiritCenter installation IP address, if not specified, it means using the PrintSpirit official website as the editing server

Then access using http://127.0.0.1:8000, which will list the labels and allow you to select, edit, add, or delete labels.

Principle

For online enterprise edition users and SpiritCenter users, "PrintSpirit" provides the following APIs:

  • /api/get-access-token Get access token, which needs to be called before calling the following APIs. The obtained token can be cached and used, with a validity period of 1 hour.
  • /api/new-label Create a new blank label or copy an existing label. Returns the ID of the newly created label, which can be saved in the database and used to edit the label at any time.
  • /api/del-label Delete a label
  • /api/get-label-list Get the list of labels
  • /api/get-label-content Get the content of a label
  • /third-edit Edit a label

Third-party websites can use the get-label-list API to obtain the full list of labels for the enterprise. An additional parameter subclass is required, which is a custom classification identifier, most commonly used to distinguish end-users under the enterprise, facilitating SaaS software development. With these APIs, third-party enterprise websites can categorize and list various label templates as needed, further enabling the selection of print templates, preview display, editing, etc.

If a third-party website needs to edit a label, it can jump to (or embed in an IFRAME) https://www.printspirit.cn/third-edit?token=__token__&subclass=__subclass__&tpid=__tpid__, to open the editor. Three parameters are required: subclass / tpid, if tpid is not set, it means creating a new label.

Third-party websites can use new-label to create a label first, obtain the ID of the newly created label, and then edit it. This way, the label ID can be saved in the system for subsequent printing, editing, and other operations.

If a third-party website needs to save label data on its own website, it can use the get-label-content API to obtain the content of the label. Note: In most cases, there is no need to save label data locally.

If a third-party website needs to preview labels on its own website, it can use <img src="https://www.printspirit.cn/utils/thumb?id=tp_id"/> (PrintSpirit official website) or <img src="http://IP:9011/utils/thumb?id=tp_id"/> (SpiritCenter)

Note: For internet mode, please register an account on "PrintSpirit" and contact customer service to enable API functionality. For testing, you can use the third_test account, the password is also third_test.

Development Tools

To facilitate the development of embedding programs, we provide development examples and SDKs:

GO-SDK

go get github.com/printspirit/gosdk

Use site = gosdk.NewThirdApp(HOST_URL, PASS, WORD) to create an instance, then call the API

func NewThirdApp(host, uid, pass string) *ThirdApp
func (app *ThirdApp) DelLabel(id string) error
func (app *ThirdApp) GetEditUrl(subclass, tpid string) (string, error)
func (app *ThirdApp) GetList(subclass string) (*[]TpInfo, error)
func (app *ThirdApp) NewLabel(name string, width, height, dpi int, subclass, refid string) (string, error)

Example Source Code

Clone the gihub source code, you can modify, compile and run the program locally.

git clone https://www.github.com/printspirit/spirit_example

The program is under the third_site directory, divided into GO and PHP versions

GO:

cd third_site\go
go build 
.\third_site.exe -p 8000 -ip ip_of_spiritcenter

PHP:

Use the built-in web service of PHP 5.4 or above.

cd third_site\php
php -S localhost:8000 main.php

For an explanation of the PHP program, please view

API Details

get-access-token

Get access token, which needs to be called before calling the following APIs. The obtained token can be cached and used, with a validity period of 1 hour.

http[s][:port]/server_IP_address/api/get-access-token?userid=XXX&passwd=XXXX

Server access URL:

Same below.

Parameter Description Example
userid Username
passwd Password

Return:

{ 
  "rc":"OK",
  "token":"5c6L3nGjDJlaGVSi_PJwVZR8..............",
  "expirt":3600
}

When rc is OK, return the token and expiration time.

new-label

http[s][:port]/server_IP_address/api/new-label?token=XXXXX&subclass=XXX...

Parameter Description Example
token Obtained through get-access-token
subclass Subclass
width Label width in 0.1mm
height Label height in 0.1mm
dpi Default resolution in dots per inch in 0.1mm
name Label name
refid Create a new label using the label specified by refid as a template If this parameter is not present, create a blank label 
{
    "rc":"OK"
	"id": 3120f21d-e33c-41ed-8f99-3e259a12f6cd 
}

Returns the label id on success, which can be used for editing and other operations

del-label

Delete a label

http[s][:port]/server_IP_address/api/del-label?token=XXXXX&subclass=XXX...

Parameter Description Example
token Obtained through get-access-token
id Label ID

get-label-list

http[s][:port]/server_IP_address/api/get-label-list?token=XXXXX&subclass=XXX

Parameter Description Example
token Obtained through get-access-token
subclass Subclass Device label

Return:

{
    "rc":"OK"
	"data":[{
        "id": "0a12953e-1379-4105-ac8a-e4cbde51c0fc", 
		"name":"Third-party interface test", 
		"memo":"Third-party interface test-template 1-save as", 
		"width":1200, 
		"height":800, 
		"subclass":"2", 
		"private":0, 
		"create_time":"2021-02-14T13:47:58Z", 
		"modify_time":"2021-02-14T13:48:50Z"
    }]
}

get-label-content

Get the content of a label.

http[s][:port]/server_IP_address/api/get-label-content?token=XXX&tpid=TPID

Parameter Description Example
token Obtained through get-access-token
tpid Label ID whose content needs to be obtained

Return:

{
	"rc":"OK",
	"tpinfo":{
		"id":"0a12953e-1379-4105-ac8a-e4cbde51c0fc",
		"name":"Third-party interface test",
		"memo":"Third-party interface test-template 1-save as",
		"dpi":203,
		"width":1200,
		"height":800,
		"subclass":"2",
		"create_time":"2021-02-14T13:47:58Z",
		"modify_time":"2021-02-14T13:48:50Z"
	},
	"data":[
		{...},
		{...}
	],
	
}

third-edit

Will jump to the PrintSpirit website or SpiritCenter server to start editing

http[s][:port]/server_IP_address/third-edit?subclass=XXXX&tpid=XXXX&token=XXXX

Parameter Description Example
token Obtained through get-access-token
subclass Subclass Device label
tpid Template id If empty, it means creating a new label

Leave Your Message

login